Skip to content

fix(BetterGI): 修复执行层排序/超时/日常连坐,修正幽境参数并恢复 MCP 初始化 - #631

Closed
TCddddd wants to merge 98 commits into
AUTO-MAS-Project:mainfrom
TCddddd:feat/bettergi-onedragon-config
Closed

TCddddd wants to merge 98 commits into
AUTO-MAS-Project:mainfrom
TCddddd:feat/bettergi-onedragon-config

Conversation

@TCddddd

@TCddddd TCddddd commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

概述

本轮针对 BetterGI 一条龙执行层的实机排障(BGI 0.64.1-alpha.1),修复执行层排序、超时与日常任务连坐问题,并按 BGI 官方 d.ts / C# 源码修正幽境危战参数透传。

主要改动

执行层排序:支持同名多实例定向排序

  • 左栏队列行新增 planUid 字段(持久化于 OneDragon.Queue),与 Plan 步骤 uid 精确绑定
  • build_combat_steps 匹配优先级:planUid 精确 > 名称精确 > 同基名 FIFO
  • 效果:三个同名「自动秘境」实例的拖拽顺序可逐实例生效,不再退化为 Plan 原顺序

执行层超时:空闲超时替代固定墙钟

  • 旧实现为固定 900s 墙钟,多实例执行层总耗时 20+ 分钟会被误杀(实机 7 步在 14 分钟处被砍,末位步骤未执行)
  • 改为空闲超时:on_log 每收到日志即续期,日志静默 300s 才判定卡死,不设总时长上限

执行层失败不再中止任务

  • 旧逻辑:执行层失败 → 整个任务中止 → 日常 4 项(邮件/尘歌壶/合成树脂/每日奖励)被连坐吞掉
  • 改为:记录警告并继续一条龙日常(日常为领奖类,与战斗无依赖)

失败判定修正

  • MAS_PLAN_FAIL / MAS_STEP_FAIL 纳入失败标记:执行层 JS 抛异常后 BGI 仍会打印「配置组 … 执行结束」,仅靠该结束标记会把失败误判为成功

幽境危战参数按 BGI 官方源码修正

  • AutoStygianOnslaughtParam 无 maxArtifactStar / combatStrategyPath 属性(源码已核实),直接赋值会抛 no suitable property or field 并中断整个执行层
  • 移除无效的 maxArtifactStar 透传(前端面板 / 后端白名单与映射 / 执行层脚本)
  • 策略改为直接调用 setCombatStrategyPath()(副作用写入 CombatScriptBagPath),改用无参构造保留 BGI 全局默认策略

组开关保存失败可见化

  • toggleGroup / applyGroupsPatch 保存失败时回滚本地状态并提示,消除「界面开着、后端没有」的静默脱节

MCP 后台初始化恢复可用

  • fastapi_mcp 的 resolve_schema_references 对互相 $ref 引用的模型无限展开(~1000 层 RecursionError),导致整个后台初始化失败(MainTimer / 通知管理器等全部跳过)
  • 加载后替换为带深度上限(96 层)的同逻辑实现,超限 $ref 原样保留;同时移除启动脚本中的 AUTO_MAS_ENABLE_MCP=0

测试情况

实机(BGI 0.64.1-alpha.1 + 本分支)验证:

  • 执行层 6 步全部 MAS_STEP_DONE(幽境危战、地脉花×2、秘境×3),无 MAS_PLAN_FAIL
  • MAS_PROP_UNSUPPORTED 守卫按预期跳过 BGI 未暴露的属性
  • 一条龙日常(邮件/每日奖励)正常承接执行

TCddddd and others added 30 commits September 4, 2026 19:58
BetterGI 鐢ㄦ埛缂栬緫椤电殑涓€鏉¢緳閰嶇疆鍖洪噸鏋勪负鍙鍖栭槦鍒楋細
- 宸︽爮闃熷垪鏀寔鎷栨嫿鎺掑簭銆佸惎鐢ㄥ紑鍏炽€佸彸閿Щ鍑轰笌涓€閿竻绌?- 娣诲姞閰嶇疆缁勬敮鎸佸€欓€夌偣鍑?鍒嗗彿鎵归噺杈撳叆锛屽彲閲嶅鍔犲叆锛堟瘡琛岀嫭绔嬪疄渚嬶級
- 鏂板銆屼綋鍔涗綔鎴樸€嶄笓椤归」锛氬惎鐢ㄦ椂鑷姩鍏抽棴骞跺喕缁撳埛鍙栫被瀹樻柟缁勶紝鍏抽棴鍚庢寜璁板繂鎭㈠
- 鍐呯疆/浣撳姏/鑷畾涔夐厤缃粍浠ャ€岄粯璁?涓撻」/鑷畾涔夈€嶅墠缂€ tag 鍖哄垎
- 队列行/详情/候选 tag 统一配色(默认=灰、专项=紫、自定义&JS=蓝、路径=绿,浅底深字)
- 队列多选修复:Shift 区间选择以 uid 锚点,普通点击保留锚点
- 默认一条龙顺序调整并同步模板 TaskOrder/后端单一来源
- 体力作战冻结名单补充「自动幽境危战」
- 添加配置组弹窗输入改为标签输入(彩色气泡+回车/分号提交+未知名称拼写检查)
- 新增任务设置:右栏按 BGI 一条龙 JSON 字段分组展示/编辑并写回 per-user 副本(含设置读写 API)
- yarn openapi 生成 BetterGIOneDragonSettingsIn/Out 模型与
  BetterGiService 的类型化 get/save 方法
- 手写 settings composable 改为调用生成的 BetterGiService,消除旁路
- 自动秘境补 SundayEverySelectedValue / SundayWeeklySelectedValue(每日/每周模式的选择序号)
- 每条内置龙右栏追加公共「完成后操作」CompletionAction(BGI 为全局卡,非任务专属)
- 依据 BGI OneDragonFlowPage.xaml 核对字段归属(领奖树脂/分解圣遗物/奖励识别属 BGI 全局 config,不在一条龙 JSON,暂不接入)
- 首领讨伐「选择首领」改为二级连列弹窗(地区 → 首领 Boss),
  首领候选按 BetterGI AutoBossData.CountryToBosses 分组(41 个,无至冬)
- 「选择战斗策略」复用已有策略弹窗:顶部通用策略与右栏字段共用一套候选
- 讨伐目标字段顺序调整为:选择首领 → 切换队伍 → 战斗策略
- 设置面板支持 strategy/boss 字段类型(点击输入框弹窗单选)
- 首领候选展示「首领名称-地区」,value 保持首领名语义
- 基于 BGI 全局 config.json 物化/还原幽境危战刷取策略与树脂次数设置
- 队列行启停开关、批量操作与标签展示细化
- 同步 res/version.json changelog
解决冲突:
- frontend/src/i18n/locales/zh-CN.ts:4 处 BetterGI 文案保留本分支的可视化队列/独立配置新文案
- res/version.json:保留双方 changelog 条目
- 新增 OneDragon.Queue 持久化可视化队列(顺序/成员/同名重复实例),运行时按队列重建一条龙 TaskOrder,为空时保持旧行为
- 前端队列拖拽/添加/移除/清空落库,加载时优先恢复持久化队列
- per-user 接口统一校验 userId 归属(UUID + UserData)与 configName 路径边界,防越权与目录穿越
- 任务收尾关闭游戏改为直接强制结束,失败原因落日志并推送调度台(拒绝访问时给出权限指引)
- 每周秘境数据源文档与实现对齐(仅官方 tp.json)
- PR changelog 合并为一条,移除误提交的本地草稿文件
- 按最新后端 openapi 重新生成 src/api:OneDragon 模型新增 Queue 持久化队列字段
- BetterGI 部分接口 userId 改为必填(带默认值),秘境/配置组接口描述与实现对齐
- 新建用户默认表单补 Queue,与后端默认值一致(空队列回退旧顺序行为)
## 摘要
- MAA 自动代理接管配置时,官服/B 服开始唤醒的账号切换开关强制写为开:MAA 内已存为关闭时不再出现只写账号名却不切号的问题;用户未填写账号时 MAA 传空账号名仍不会实际切号。
- res/version.json 在 v5.5.0-beta.3 程序优化节补一条记录。
启动等待画面上的「查看日志」点开是一片空白,后端启动失败后这个入口又整个消失;日志文件打不开时也不会有任何提示。

- **日志窗改为落在前端日志**。日志页默认选中
`debug/app.log`,而启动这一程后端还没起来,这个文件不存在或停在上一轮;启动过程的记录都在主进程写的
`debug/frontend.log` 里。`createLogWindow(file)` 支持 `#/logs?file=frontend`
落地,窗口已经开着时由主进程推送 `log:selectFile` 换文件(只 focus
的话,之前停在后端日志的窗口再点一次仍然是空的);`openLaunchLogWindow()` 固定传
`frontend`,不带参数打开时默认不变。日志为空时给一句提示,不再是空白的 Monaco。
- **后端启动失败那一屏补上「查看日志」**。`buildRuntimeStartFailure` 不带
`logPath`,`RUNTIME_NOT_FOUND` 这类 spawn 之前的失败连日志正文都没有,`hasDetails` 为
false,整屏只剩「重试」和「查看排障文档」。沿用等待态同一个入口,`LaunchFailure` 未改动。
- **失败态正文改为上下居中**。`.failure-body` 原先是 `align-self: flex-start`,被
`.launch-page` 的 `place-items: center` 撑满高度后一直贴顶。用 `margin-block: auto`
而不是 `align-items: center`——后者在内容超过窗口高度时会裁掉顶部、滚不上去。
- **两处让日志打不开还不提示的问题**。其一,`initializeLogger()` 把 `frontend.log` 写到
`dirname(app.getPath('exe'))`(源码运行下是
`node_modules/electron/dist/`),而日志窗读的是
`getAppRoot()`,`initializationHandlers` 的 `fallbackLogPath`
同一处口径不一致,两处统一到 `getAppRoot()`,打包版路径不变。其二,`shell.openPath()` 失败时是 resolve
一条错误信息而不是 reject,`open-file` handler 丢掉了这个返回值,调用方 `catch`
不到——「打开日志失败」的提示从来没出现过,历史记录页还会照常弹「日志文件已打开」;改为按相邻 `open-url` 的约定返回 `{
success, error }`,两处调用方跟着判断。

本地验证(在 `frontend/`):`yarn typecheck`、`yarn build:main`、`yarn lint`
均无输出;`yarn test` 402 通过。剩下 3
个失败(`electron/services/runtimeInitializationService.test.ts`
×2、`electron/services/backendService.test.ts` ×1)在 dev 上就是红的——本 PR 动了
`frontend/electron/`,所以把 electron 侧改动整体还原后单独重跑了这两个套件,失败项完全一致。

另外用 `vite build` + `electron .`
起了一次真实窗口核对失败态:`AUTO_MAS_RUNTIME_MODE=managed` 且没有 Runtime 时落在
`RUNTIME_NOT_FOUND` 失败屏,文字块上下、左右均居中;点「打开日志」正常拉起
`<appRoot>/debug/frontend.log`(这个文件本身就是上面路径口径修复的产物,改之前源码运行下不会存在)。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
## 问题

脚本侧的守卫(如 MaaEnd 分辨率不达标时的强停)会调 `PostStop` 停掉整个 tasker。强停是由 pipeline
里的动作节点触发的,那个节点自身返回成功,MaaFW 于是把入口回报成 `Tasker.Task.Succeeded`;runner 只看
`job.failed`,把一件没做的事记成「任务完成」,还继续投递剩余任务,每个重复一遍。

实际现场(2026-09-07 04:00,MaaEnd 12 个任务):11 个被记成完成,只因为其中一次投递恰好撞上 tasker 正在
stopping、报了 `task_id=0` 才暴露。**否则整轮会被报成全部成功。**

## 判据为什么不用事件

第一版想监听 `MaaTaskerPostStop` 事件,但它比 `job.wait()` 返回晚约 19ms:

```
[04:00:31.772] 任务完成: 🤝拜访好友
[04:00:31.791] [MaaFW Tasker] 开始: MaaTaskerPostStop
```

光靠事件会漏掉当前这个任务,正好是要修的那个。改用同步查询 `MaaTaskerStopping`——`post_stop` 因果上必然早于
`wait()` 返回,此刻 `stopping` 一定还是
true。事件标志降级为兜底,覆盖两个任务之间到达的强停;`_stop_requested` 排除 MAS 自己发起的停止。

命中后:当前任务按失败记录、不计入 `completedTasks`,剩余任务不再投递。`task_id=0`
那条也一并收编,它本来就是「投递撞上 stopping」的表现。

## 本地验证

在本分支的 `.venv`(Python 3.12)实跑:

| 检查 | 结果 |
| --- | --- |
| `python -m pytest tests` | 484 passed, 3 skipped |
| `python -m pytest tests --collect-only -q` | 487 collected,退出 0 |
| `ruff check` / `ruff format --check` | 通过 |
| 回归测试 7 例(边界测试,按 `tests/AGENTS.md` 未提交) | 7 passed |

回归测试含一条敏感性检查:把新判据短路成恒 `False`,断言旧行为下 3 个任务全被记成「完成」——确认这组用例确实能捕获该
bug,而不是修复前后都绿。

## 残留风险

判据是「tasker 被停 → 当前任务算失败」。如果某个项目把 `PostStop`
当**正常收尾**用,它的末尾任务会从「完成」变成「失败」。MaaEnd 里 `PostStop` 只挂在
`__SceneCheckAbortPipeline` 一个节点上,是纯 abort 用法;其他项目未逐一核查。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Sourcery 总结

防止由脚本触发的 tasker 停止操作被报告为成功任务,并阻止剩余任务继续运行。

Bug 修复:
- 将脚本触发的 MaaFramework 停止操作视为任务失败,而不是成功完成,从而避免将未完成的任务计为成功,或提交后续任务。

增强功能:
- 通过检查 tasker 的停止状态同步检测外部停止操作,并保留事件通知作为后备机制,同时排除由 MAS 自身发起的停止操作。

<details>
<summary>Original summary in English</summary>

## Sourcery 摘要

防止由脚本触发的 tasker 停止被报告为成功任务,并阻止剩余任务队列继续执行。

Bug 修复:
- 将由脚本触发的 MaaFramework tasker
停止视为任务失败,而不是成功完成,从而避免将未完成的工作记录为已完成,或提交后续任务。

改进:
- 通过 tasker 状态同步检测外部触发的停止,并以基于事件的方式进行回退,同时区分由 MAS 发起的停止。

日常维护:
- 更新应用程序版本元数据。

<details>
<summary>Original summary in English</summary>

## Summary by Sourcery

Prevent script-triggered tasker stops from being reported as successful
tasks and from allowing the remaining task queue to continue.

Bug Fixes:
- Treats script-triggered MaaFramework tasker stops as task failures
instead of successful completions, preventing unfinished work from being
recorded as completed or subsequent tasks from being submitted.

Enhancements:
- Detects externally triggered stops synchronously through tasker state
with event-based fallback, while distinguishing MAS-initiated stops.

Chores:
- Updates the application version metadata.

</details>

</details>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
- 首页快速启动支持一次选择并启动多个任务。
- 记住上次选择,下次进入首页时自动恢复。
- 本地验证:yarn test src/views/home/homeQuickStartTasks.test.ts
src/views/home/components/HomeCommandCard.test.ts;yarn typecheck;yarn
lint。

## Sourcery 总结

支持从主页快速启动多个任务,并在用户再次访问时记住其有效选择。

新功能:
- 支持一次操作选择并启动多个主页快速启动任务,并分别反馈每个任务的成功或失败结果。
- 持久化所选快速启动任务 ID,并在返回主页时恢复有效选择。

增强功能:
- 过滤无效、占位、重复和不可用的快速启动选择,同时保留选择顺序。
- 当单个快速启动任务失败时,继续启动其余任务。

测试:
- 增加对多选渲染、选择规范化、不可用任务过滤以及批量启动结果的覆盖。

维护:
- 为批量启动结果添加本地化消息,并重新格式化受影响的语言环境条目。

<details>
<summary>Original summary in English</summary>

## Sourcery 摘要

支持多任务主页快速启动,并持久化、验证所选任务,同时提供各任务的启动反馈。

新功能:
- 支持在单次操作中选择并启动多个主页快速启动任务。
- 持久化所选快速启动任务的 ID,并在重新访问主页时恢复这些选择。

Bug 修复:
- 在显示或启动任务之前,过滤持久化选择中的无效、占位、重复和不可用任务。
- 当某个快速启动任务失败时,继续启动其余任务。

增强功能:
- 报告批量启动的任务数量,并使用本地化消息提供单个失败任务的详细信息,同时保留选择顺序。

测试:
- 增加对多选渲染、选择规范化、不可用任务过滤和批量启动结果的覆盖。

杂项:
- 重新格式化受影响的语言环境条目,并添加本地化的批量启动消息。

<details>
<summary>Original summary in English</summary>

## Sourcery 摘要

支持从主页持久化启动多个任务,同时验证选择内容并报告每个任务的启动结果。

新功能:
- 支持通过单次操作选择并启动多个主页快速启动任务。
- 持久化快速启动选择,并在返回主页时恢复有效选项。

错误修复:
- 在显示或启动前,过滤无效、占位、重复以及不可用的持久化选择。
- 当某个快速启动任务失败时,继续启动其余任务。

增强功能:
- 保留选择顺序,并为批量启动提供本地化的汇总成功反馈和逐任务失败反馈。

测试:
- 增加对多选渲染、选择规范化、不可用任务过滤以及批量启动结果的覆盖。

杂项:
- 重新格式化受影响的语言环境条目,并添加本地化的批量启动消息。

<details>
<summary>Original summary in English</summary>

## Sourcery 摘要

支持从主页持久化启动多个任务,同时验证选择内容并报告每个任务的启动结果。

新功能:
- 支持在一次操作中选择并启动多个主页快速启动任务。
- 持久化所选快速启动任务的 ID,并在返回主页时恢复有效的选择。

错误修复:
- 在显示或启动快速启动任务之前,过滤无效、占位、重复和不可用的选择。
- 即使某个快速启动任务失败,也继续启动其余任务。

增强功能:
- 提供按顺序排列的批量启动结果,包括本地化的成功数量和每个任务的失败详情。

测试:
- 增加对多选渲染、选择规范化、不可用任务过滤以及批量启动结果的覆盖。

维护:
- 添加本地化的批量启动反馈,并重新格式化受影响的语言环境条目。

<details>
<summary>Original summary in English</summary>

## Sourcery 摘要

支持从主页可靠地快速启动多个任务,同时保留用户选择并报告启动结果。

新功能:
- 支持一次操作选择并启动多个主页快速启动任务。
- 持久化快速启动选择,并在返回主页时恢复有效选项。

Bug 修复:
- 在显示或启动前,过滤无效、占位、重复及不可用的快速启动选项。
- 当单个快速启动任务失败时,继续启动其余任务。

改进:
- 提供有序的批量启动结果,包括本地化的成功数量和每个任务的失败详情。

测试:
- 增加对多选渲染、选择规范化、不可用任务过滤及批量启动结果的覆盖。

杂项:
- 添加本地化的批量启动反馈,并重新格式化受影响的语言环境条目。

<details>
<summary>Original summary in English</summary>

## Sourcery 摘要

支持从主页可靠地快速启动多个任务,同时保留有效的用户选择并报告启动结果。

新功能:
- 支持在一次操作中选择并启动多个主页快速启动任务。
- 持久化所选快速启动任务 ID,并在返回主页时恢复有效的选择。

错误修复:
- 在显示或启动前,过滤无效、占位、重复和不可用的快速启动选项。
- 当单个任务失败时,继续启动其余任务。

增强功能:
- 提供按顺序排列的批量启动结果,包括本地化的成功数量和每个任务的失败详情。

测试:
- 增加对多选渲染、选择规范化、不可用任务过滤和批量启动结果的覆盖。

杂项:
- 添加本地化的批量启动反馈消息,并重新格式化受影响的语言环境条目。

<details>
<summary>Original summary in English</summary>

## Sourcery 总结

支持从主页可靠地快速启动多个任务,同时保留有效的用户选择并报告启动结果。

新功能:
- 支持在一次操作中选择并启动多个主页快速启动任务。
- 持久化所选快速启动任务 ID,并在返回主页时恢复有效选择。

错误修复:
- 在显示或启动任务之前,过滤无效、占位、重复和不可用的选择。
- 当单个快速启动任务失败时,继续启动其余任务。

增强功能:
- 提供有序的批量启动反馈,包括本地化的成功数量和每个任务的失败详情。

测试:
- 增加对多选渲染、选择规范化、不可用任务过滤和批量启动结果的测试覆盖。

维护:
- 添加本地化的批量启动消息,并重新格式化受影响的语言环境条目。

<details>
<summary>Original summary in English</summary>

## Sourcery 总结

支持从主页可靠地快速启动多个任务,同时保留有效的选择并报告启动结果。

新功能:
- 支持在一次操作中选择并启动多个主页快速启动任务。
- 持久化所选任务 ID,并在返回主页时恢复有效的选择。

错误修复:
- 在显示或启动前,过滤无效、占位、重复以及不可用的快速启动选择。
- 当某个任务启动失败时,继续启动其余任务。

增强功能:
- 提供有序的批量启动反馈,包括本地化的成功数量和每个任务的失败详情。

测试:
- 增加对多选渲染、选择规范化、不可用任务过滤以及批量启动结果的测试覆盖。

维护:
- 添加本地化的批量启动消息,并重新格式化受影响的语言环境条目。

<details>
<summary>Original summary in English</summary>

## Sourcery 摘要

支持从主页可靠地快速启动多个任务,同时保留有效选择并报告启动结果。

新功能:
- 支持在一次操作中选择并启动多个主页快速启动任务。
- 持久化选中的快速启动任务 ID,并在返回主页时恢复有效选择。

错误修复:
- 在显示或启动任务之前,过滤无效、占位、重复和不可用的选择。
- 当单个快速启动任务失败时,继续启动其余任务。

增强功能:
- 提供有序的批量启动反馈,包括本地化的成功数量和每个任务的失败详情。

测试:
- 增加对多选渲染、选择规范化、不可用任务过滤和批量启动结果的覆盖。

维护工作:
- 添加本地化的批量启动消息,并重新格式化受影响的语言环境条目。

<details>
<summary>Original summary in English</summary>

## Summary by Sourcery

Support reliable multi-task quick starts from the home page while
preserving valid selections and reporting launch results.

New Features:
- Enable selecting and launching multiple home quick-start tasks in one
action.
- Persist selected quick-start task IDs and restore valid selections
when returning to the home page.

Bug Fixes:
- Filter invalid, placeholder, duplicate, and unavailable selections
before displaying or launching tasks.
- Continue launching remaining tasks when an individual quick-start task
fails.

Enhancements:
- Provide ordered batch launch feedback with localized success counts
and per-task failure details.

Tests:
- Add coverage for multi-select rendering, selection normalization,
unavailable-task filtering, and batch launch outcomes.

Chores:
- Add localized batch-launch messages and reformat affected locale
entries.

</details>

</details>

</details>

</details>

</details>

</details>

</details>

</details>

</details>
…lan 鐨?weeklyDomain/weeklyLeyLine 宓屽骞跺洖鏄捐繕鍘燂紙鍓嶇闆舵敼鍔級锛宮ain.js 鎸夊綋澶╂槦鏈熷彇鍊肩洿浼狅紝绉樺褰撳ぉ鏃犻厤缃垯璺宠繃锛涗慨澶嶇┖ Plan 鎴栦粎鏈?weekly 鏃?merge 涓㈠け鏁版嵁鐨?bug
## 问题

Runtime 自 `5deb1d8` 起会为 `uv.download` 发真实字节百分比,且下载器在写入末块时**必定**强制回报一次
100。桥接层原样透传,`useInitializationFlow` 见到 `>= 100` 就把当前段标成完成——**uv
下载完末字节的瞬间「安装 Python」就显示完成**,而 SHA-256 校验、解压、`uv --version` 实测都还没跑;紧接着
`python.*` 的事件没有 percent,进度又被压回段起始值 10。

`repair` 与 `environment ensure` 链路中间没有 workspace 段隔开,`python.*`
直接落回同一段,所以这个倒退会停满整个 Python 重装(受限网络下是 20.9 MiB 的下载时长)。镜像轮换让下载从 0
重来时,界面还会出现可见的百分比倒退。

## 改动

- running 的百分比钳在 `[10, 99]`,100 只由段收口发出——一个界面段里装着好几个 Runtime
stage,段没结束就不能让渲染层看到 100
- 段内记录已发出的最高进度,保证只增不减
- 段开始时带着真实百分比仍照发(AUTO-MAS-Project#570 起的既有行为),只是同样受上限约束

只改桥接层与它的测试,渲染层未动。

## 本地验证

`D:\...\frontend`,corepack yarn 4.9.1 / vitest 4.1.9:

- `corepack yarn test`:44 文件 / 414 用例,413 通过
- `corepack yarn typecheck`:exit 0
- `corepack yarn lint`:exit 0

新增三条桥接层用例(末块 100 不提前收口、repair 顺序不倒退、镜像轮换不倒退),在改实现前均为红。

两点需要说明:

1. **另对齐了两条既有期望值**:`repository started` 的 `progress` 10 → 43、`dependency
started` 的 `toEqual` 补 `indeterminate: true`。这两条自 AUTO-MAS-Project#570 起就与实现不符、**在 dev
基线上本来就是红的**,本次未改变任何行为。
2. **`backendService.test.ts > managed 模式 > 不传 --repo…` 5 秒超时是基线
`48ed4ccc` 上的既有失败**:把本 PR 改动的两个文件临时换回 dev 原版复跑,仍然红。本 PR 不处理。

未做:没有真机跑过带真实字节进度的 Runtime 初始化看界面表现,结论来自单元测试与渲染层代码路径。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Sourcery 总结

通过将 100% 保留给已完成的阶段,并防止阶段内的进度回退,确保运行时引导进度准确。

Bug 修复:
- 防止运行时下载完成百分比过早将 Python 安装进度阶段标记为已完成。
- 在下载重试以及后续不带百分比的事件发生时,保持每个引导阶段内的进度单调递增。

增强功能:
- 将进行中的进度保持在 100% 以下,并仅将 100% 保留给阶段完成,同时保留实际的起始百分比。

测试:
- 添加桥接测试,覆盖下载完成处理、修复进度单调性和镜像轮换重试。

维护:
- 根据当前行为调整现有进度桥接测试的预期。

<details>
<summary>Original summary in English</summary>

## Summary by Sourcery

Keep runtime bootstrap progress accurate by reserving 100% for completed
segments and preventing progress regressions within a segment.

Bug Fixes:
- Prevent runtime download completion percentages from prematurely
marking the Python installation progress segment as complete.
- Preserve monotonic progress within each bootstrap segment across
download retries and subsequent events without percentages.

Enhancements:
- Keep running progress below 100 and reserve 100 exclusively for
segment completion while preserving real starting percentages.

Tests:
- Add bridge tests covering download completion handling, repair
progress monotonicity, and mirror-rotation retries.

Chores:
- Align existing progress bridge test expectations with current
behavior.

</details>

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
## 问题

MAA 卡死后不会被判定为超时,任务一直挂着。

## 根因

`is_log_stalled` 只用 `latest_time` 判断"有没有推进"。MAA 卡死时每隔提醒间隔(默认 30 分钟)会往
`gui.log` 写一条停滞提示,这条"没有推进"的提示反而刷新了 `latest_time`,把计时反复重置。

`AutoProxyTask.prepare()` 的 `except_logs` 本来就防了这一手,但它只匹配旧版 MAA
`TaskTimeoutWarning` 的中文文案;MAA 后来把该功能重写为
`TaskStallWarning`、文案全换,豁免静默失效——没有报错,只是超时不再触发。

只有超时阈值大于提醒间隔的模式受影响:剿灭 `AnnihilationTimeLimit` 默认 40 分钟、命中热更新时放宽到
`GameUpdateTimeLimit` 默认 60 分钟,都永远判不出超时;日常 `RoutineTimeLimit` 默认 10
分钟,第一条提示还没来就先超时了,不受影响。

实测日志(MAA v6.17.2,剿灭模式):`17:10:38` 最后一条正常行,之后 4 小时 25 分只剩每 30
分钟一条停滞提示,全程无超时判定。

## 改动

`except_logs` 换成模块级常量 `_MAA_STALL_NOTICE_MARKERS`,收录
`TaskStallWarning`(现行)与 `TaskTimeoutWarning`(旧版)× 简中 / 繁中 / 英 / 日 / 韩共
10 条不含 `{0}`/`{1}`
变量的固定片段。韩文旧文案句中有换行,换行后那半是无时间戳的独立行、本就进不了时间戳解析,只取带时间戳那半行的结尾。

10 条片段均已拿到两代 MAA 的全部 5 个 `Localizations/*.xaml`
里核对:每条恰好命中目标那一条本地化字符串,跨版本互不误伤,也不误伤其它消息——片段若误伤正常日志行会造成假阳性超时,比漏判更糟。

## 本地验证

环境:本工作树 `.venv`(Python 3.12.13),基线 `dev@48ed4cc`

```
python -m pytest tests                    → 493 passed, 3 skipped, 107 subtests passed
python -m pytest tests --collect-only -q  → 496 collected, exit 0
ruff check app/task/MAA/AutoProxy.py      → All checks passed
```

(基线为 489 passed / 97 subtests,增量来自下述本地测试。)

按 `tests/AGENTS.md`,bug 边界测试仅本地运行、未提交。该测试不自己拼 `except_logs`,而是 patch 掉
`LogMonitor` 后跑真实的 `prepare()` 捕获实参。反向验证:把 `except_logs` 改回修复前那一行,10
个用例失败,唯一仍通过的是
`TaskTimeoutWarning/zh-cn`——正是修复前就在豁免列表里的那一条。端到端用例按实测日志序列(每 30 分钟一条提示、40
分钟阈值)跑出 `[False, False, True, True]`,55 分钟处开始报超时。

## 遗留

判据形态本身仍与 MAA 的文案原文耦合,MAA
下次改这段文案还会同样静默失效(这已是第二次)。根治需要换判据(例如只认任务链推进类日志),不在本 PR 范围内。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Sourcery 总结

确保当重复的停滞通知是后续唯一日志输出时,MAA 任务能够超时。

错误修复:
- 防止 MAA 停滞通知刷新日志活动时间戳,使真正停滞的任务能够达到超时阈值。
- 在支持的语言中识别当前和旧版 MAA 的停滞警告消息,同时保持与旧版 MAA 的兼容性。

<details>
<summary>Original summary in English</summary>

## Summary by Sourcery

Ensure MAA tasks can time out when repeated stall notices are the only
subsequent log output.

Bug Fixes:
- Prevent MAA stall notices from refreshing log activity timestamps so
genuinely stalled tasks can reach the timeout threshold.
- Recognize current and legacy MAA stall-warning messages across
supported languages while preserving compatibility with older MAA
versions.

</details>

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
qiyinxi and others added 29 commits September 9, 2026 19:13
主页卫星的脚本类型清单是手工维护的,和 `SCRIPT_LOGOS` 平行存在。它是普通数组,少一个不报错;末尾还有一句
`.filter(module => module.iconUrl !== '')`,图标文件名写错就静默丢掉,连日志都没有。

因此漏过三次:

```
4fb31ef  hotfix: 补充NTE新主页入口,补充HSR和NTE的卫星图
a5cfad2  fix(home): 首页卫星补上 MaaFW,否则它跑起来首页没有反馈
```

改成从 `SCRIPT_LOGOS` 取图标。它声明成 `Record<ScriptType, string>`,新增脚本类型时不补图标会当场
typecheck 报错,漏不掉。

原有的轨道排列顺序保留,但它降级成纯观感项、不再是白名单——没列进顺序表的类型排在后面,所以下一个新脚本不动这里也会自动上轨。

通用脚本仍然不上轨道,理由写进了注释:它在 `SCRIPT_LOGOS` 里用的就是
`AUTO-MAS.ico`,也就是卫星圈的中心图标,放上去会出现一颗和中心一模一样的卫星。

测试从「只断言 Okww 存在」改成钉住「除显式排除的以外,每个脚本类型都有卫星」。

**用户可见行为不变**:仍是同样 10 颗卫星、同样顺序,所以 changelog 记在「开发流程」。

## 验证

| 检查 | 结果 |
| --- | --- |
| `yarn vitest run src/composables/satellite-config.test.ts` | 5 passed
|
| `yarn typecheck` | exit 0 |
| `yarn lint` | exit 0 |

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Sourcery 摘要

从集中式脚本图标注册表中获取首页卫星图标,确保新脚本类型不会被悄然遗漏。

错误修复:
- 确保除明确排除的通用脚本外,每种脚本类型都作为首页卫星显示,并且具有非空图标。

增强功能:
- 使用集中式脚本图标注册表提供首页卫星图标,同时保留现有的轨道顺序,并自动将新添加的类型排列在之后。
- 强化卫星配置测试,以检测缺失的脚本覆盖范围和无效图标。

测试:
- 更新卫星配置测试,以验证完整的脚本覆盖范围、图标可用性、排除项和排序。

<details>
<summary>Original summary in English</summary>

## Summary by Sourcery

Source homepage satellite icons from the centralized script icon
registry so new script types cannot be silently omitted.

Bug Fixes:
- Ensure every script type except the explicitly excluded general script
appears as a homepage satellite with a non-empty icon.

Enhancements:
- Use the centralized script icon registry for homepage satellite icons
while preserving the existing orbit order and automatically placing
newly added types afterward.
- Strengthen satellite configuration tests to detect missing script
coverage and invalid icons.

Tests:
- Update satellite configuration tests to validate complete script
coverage, icon availability, exclusions, and ordering.

</details>

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
全局设置的「虚拟显示器」说明里写着「需先自行安装 Parsec
虚拟显示驱动」,但下载入口只出现在驱动检测不通过时的那条告警里,已经装好驱动的人反而无处可点。现在那句话本身就是链接,点击用系统默认浏览器打开。

顺带把原来钉在 `v0.45.1` 的安装包直链换成 `releases/latest`:直链会随上游发版失效,点下去也是直接落一个
exe,用户没机会先看清自己在装什么。

中英日三套词表都改成 `{driverLink}` 占位符(句中位置与标点各语言不同,用 `<i18n-t>`
而非拼接多段词条)。本地起前后端逐语言看过渲染与点击目标,`yarn typecheck` / `yarn lint` 均退出 0。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Sourcery 总结

将虚拟显示驱动程序要求改为指向 GitHub 最新版本发布页面的本地化链接。

新功能:
- 在中文、英文和日文的全局设置说明中,使 Parsec 虚拟显示驱动程序要求可直接点击。
- 打开最新的 Parsec 虚拟显示驱动程序发布页面,而不是固定版本的安装程序下载链接。

错误修复:
- 确保已安装驱动程序的用户仍可通过虚拟显示说明访问驱动程序下载。

文档:
- 在更新日志中记录新的虚拟显示驱动程序下载入口。

<details>
<summary>Original summary in English</summary>

## Summary by Sourcery

Make the virtual display driver requirement a localized link to the
latest GitHub release page.

New Features:
- Make the Parsec virtual display driver requirement in the global
settings description directly clickable in Chinese, English, and
Japanese.
- Open the latest Parsec virtual display driver release page instead of
a version-pinned installer download.

Bug Fixes:
- Ensure users who already have the driver installed can still access
the driver download from the virtual display description.

Documentation:
- Document the new virtual display driver download entry in the
changelog.

</details>

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
## 摘要

- MFW 用 Adb controller 时只开模拟器,游戏要等脚本自己那套流程冷启动。现在启动模拟器时可一并把游戏拉起来,接上 AUTO-MAS-Project#635
的模拟器带包启动能力。
- 包名默认从项目里自动识别:`interface.json` 中并没有包名字段(ProjectInterface
规格里就没有这一项),真正的包名写在 pipeline 节点的 `StartApp` 动作参数里。M9A 的九个服各自在
`resource/<服>/pipeline/startup.json` 覆盖同一个节点,靠 `resource[].path`
顺序叠加;MaaEnd 则放在 option 的 `pipeline_override` 里、取决于所选
`ClientVersion`。两种放法都已覆盖。
- 这是约定而非契约,因此识别不出、或识别到多个互相矛盾的包名时一律不猜,回落到手动填写并在运行日志中说明原因。配置只新增
`Game.PackageName` 一项:填了即手动覆盖,留空即自动识别,同一概念不让用户选两次。
- 顺带修正任务前后脚本的触发次数:此前前脚本在重试循环内、后脚本在每次尝试的 `finally`
内,一个用户重试三次就各跑三遍;现改为每用户各一次。后脚本仍保留在 `finally`,成功、重试全败与中途取消都会跑到。

## 本地验证

包名识别对着两个真实项目逐项实跑:

| 项目 | 结果 |
| --- | --- |
| M9A 九个服(官服 / B 服 / OPPO / 小米 / 华为 / EN / JP / KR / 港澳台) | 各自得到正确包名,含
`base + global_jp + global_en` 这类三层叠加 |
| MaaEnd 五个 option case(CN / Bilibili / Global / VN / Cloud) | 各自得到正确包名
|
| 顺序敏感性 | 颠倒 `resource[].path` 顺序会得到上一层的包名,符合覆盖语义 |
| 冲突与空输入 | 分别得到 `ambiguous`(附候选列表)与 `not-found`,均不猜测 |

前后脚本改动实跑 `main_task` 三条路径对照:

| 场景 | 改动前 | 改动后 |
| --- | --- | --- |
| 第一次即成功 | 前 1 次 / 后 1 次 | 前 1 次 / 后 1 次 |
| 重试 3 次全失败 | 前 3 次 / 后 3 次 | 前 1 次 / 后 1 次 |
| 首次尝试时取消 | 前 1 次 / 后 1 次 | 前 1 次 / 后 1 次,`CancelledError` 仍正常外抛 |

自动化:`python -m pytest tests` 744 passed / 3 skipped(新增 13 个纯逻辑用例 + 8
subtests,并更新既有 `test_maafw_config` 的字段数量断言);收集门槛 `--collect-only` 747
条退出码 0;`ruff format --check` 与 `ruff check` 对改动文件无问题;`python
scripts/changelog.py check` 退出码 0。前端 `yarn typecheck`、`yarn lint`
无问题,OpenAPI 由生成器更新(生成物为 CRLF,已按仓库行尾归一化,净差异仅 `MaaFWConfig_Game.ts` 一个文件)。

## 已知问题(均非本 PR 引入)

- `frontend/electron/services/backendService.test.ts` 有一个用例稳定超时失败;本 PR
未改动 `frontend/electron/` 下任何文件。
- 后端 `tests/task/test_maafw_embedded_prepare_cancel.py` 的三个用例在仅按 `uv
sync --group dev` 建立的环境下失败,原因是 `dev` 依赖组未包含 `pytest-asyncio`;补装后全部通过,上述
744 即为补装后的结果。
- 任务前后脚本的触发口径在各专项间并不一致(MAA 与 HSR 为每用户一次,其余七个在重试循环内;取消时跑收尾脚本的此前仅 MaaFW
一家)。本 PR 只调整 MaaFW,统一其余专项宜另行处理。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Sourcery 摘要

允许 MFW 模拟器运行自动启动已配置的游戏,并执行按用户划分的生命周期脚本,同时避免重试导致脚本重复执行。

新功能:
- 启用 MFW ADB 模拟器启动时同时启动关联的 Android
游戏,支持使用手动配置的软件包名称,或通过基于项目的安全自动检测来确定软件包名称。
- 添加 `Game.PackageName` 设置及相应的界面、API 模型和本地化说明,以支持手动覆盖或在必要时回退到自动检测。

错误修复:
- 防止 MFW
任务前置脚本和任务后置脚本在每次重试时重复运行,改为每个用户仅执行一次,同时保留在成功、失败和取消情况下执行任务后置脚本的行为。

增强功能:
- 从分层资源管道和任务管道覆盖配置中检测游戏软件包;当未找到软件包或发现冲突的软件包时拒绝猜测,并在任务日志中报告检测结果。

文档:
- 在变更日志中记录新的 MFW 模拟器游戏启动行为以及按用户执行脚本的语义。

测试:
- 增加对软件包规范化、管道提取、资源分层、任务覆盖、歧义处理、数据缺失和无法读取的管道文件的测试覆盖。
- 更新 MFW 配置清单预期,以包含新的游戏软件包设置。

<details>
<summary>Original summary in English</summary>

## Sourcery 摘要

允许 MFW 模拟器会话自动启动游戏,同时使生命周期脚本按每位用户执行一次,而不是每次重试执行一次。

新功能:
- 支持 MFW ADB 模拟器运行在启动模拟器的同时启动已配置的 Android 游戏,可使用手动指定的包名或基于项目的安全自动检测。
- 在后端、API 模型、前端配置和本地化 UI 中新增 `Game.PackageName` 设置。

错误修复:
- 确保 MFW 的每用户 before-task 和 after-task 脚本按每位用户执行一次,而不是在重试时重复执行,同时保留
after-task 脚本在成功、失败和取消情况下的执行。

增强功能:
- 从分层资源管道和选定的任务覆盖设置中检测游戏包,并在候选项缺失或冲突时报告问题,而不是进行猜测。

文档:
- 在更新日志中记录新的 MFW 模拟器游戏启动行为以及按用户执行一次的生命周期脚本语义。

测试:
- 增加对包名规范化、管道提取、分层资源和任务覆盖解析、歧义处理、数据缺失以及无法读取管道文件的测试覆盖。
- 更新 MFW 配置清单预期,以包含新的游戏包设置。

<details>
<summary>Original summary in English</summary>

## Summary by Sourcery

Allow MFW emulator sessions to launch their game automatically while
making lifecycle scripts execute once per user rather than once per
retry.

New Features:
- Enable MFW ADB emulator runs to launch the configured Android game
alongside the emulator, using a manual package name or safe
project-based auto-detection.
- Add the Game.PackageName setting across backend, API models, frontend
configuration, and localized UI.

Bug Fixes:
- Ensure MFW per-user before-task and after-task scripts execute once
per user instead of repeating on retries, while preserving after-task
execution on success, failure, and cancellation.

Enhancements:
- Detect game packages from layered resource pipelines and selected task
overrides, reporting missing or conflicting candidates without guessing.

Documentation:
- Document the new MFW emulator game-launch behavior and per-user
lifecycle script semantics in the changelog.

Tests:
- Add coverage for package normalization, pipeline extraction, layered
resource and task override resolution, ambiguity handling, missing data,
and unreadable pipeline files.
- Update MFW configuration inventory expectations for the new game
package setting.

</details>

</details>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
…TO-MAS-Project#641)

对 dev 做了一轮全量静态审计(主页 / M9A / MFW / HSR),这个 PR
收的是其中已经核实、且改动自洽的那批。每条都在正文里给了触发路径,不是「看着像」。

## 需要留意的两处行为变更

**HSR 周标记的翻页时刻后移四小时。** 原先按东八区自然周算,实际游戏在服务器时间周一 04:00 才重置。改用
UTC+4(其零点正是重置时刻)后,存量用户的「本周已完成」状态会有一次跳变:周一 00:00~04:00
这个窗口内,标记从「新一周」变回「上一周」。这正是要修的东西——原先这个窗口里跑的那轮,会把上一周已完成的结果写成新一周的完成态,等游戏真重置后整周都不再尝试。

**MFW 的控制方式不再被残留的模拟器选择覆盖。** 那些「选了 Win32 但一直在按 ADB 运行且没察觉」的存量脚本,行为会当场变成按
Win32 跑。

## MFW

- **worker 跑的是安装包自带的旧引擎代码。** 受 Runtime 监督时后端工作目录是 `<app-root>`、源码在
`<app-root>/repo/`,而 `<app-root>` 下还有安装包自带的那棵源码树(只随整包安装更新)。worker 以
`python -m` 启动,cwd 被插到 `sys.path[0]` 且排在 `PYTHONPATH`
之前,于是导入旧那份。现场实测:后端跑 beta.3、worker 跑 beta.2,仅 `app/task/MaaFW` 子树就差 41 个
`.py`(含
`runner/environment.py`、`interface/loader.py`、`task_config.py`)。不报错,但
MFW 引擎侧的修复永远等不到热更新生效。改为 `SOURCE_ROOT` + `PYTHONSAFEPATH=1`;worker 的 cwd
保持不变,因为运行池、更新缓存等用户数据都按它解析。`PYTHONSAFEPATH` 不透传给项目 Python agent——agent
靠脚本目录进 `sys.path[0]` 才能 import 同级模块。
- **模拟器的「最大等待时间」对 MFW 从未生效。** `MaaFWDeviceConfig` 有两份同名类,`models` 那份有
`adbReadyTimeout`、`runner` 那份没有;宿主按前者序列化 job、worker 按后者反序列化,pydantic 默认
`extra="ignore"` 静默丢掉,等 ADB 就绪一直用常量 180 秒。删掉重复定义统一从 `models` 导入。
- **项目跑过一次后,Mirror 酱的增量更新永远校验失败。** 指纹把
`debug/`、`config/maa_option.json`、`__pycache__` 算进哈希,而 runner
每次启动都会写它们;基线对不上又没有回退全量包的分支,于是再也装不上更新。新增 `FINGERPRINT_IGNORED_*` 单独排除,没动
`RESERVED_PROJECT_DIRS`——那个还用于拒绝更新包写入保留路径,塞进去会让本来就带 `config/` 的合法包装不上。
- **选了 Win32 仍按 ADB 运行。** 运行时把「配了模拟器」排在用户显式选的 controller 前面;而 Win32
分支下模拟器下拉被隐藏,用户没有入口清掉旧的 `Emulator.Id`。改为显式选择优先,并在前端切到非 ADB 时清空模拟器选择。

## HSR

- **周常与历战余响的「本周已完成」提前四小时翻页**(见上)。三处改用 UTC+4 并抽出 `_server_day_clock`
统一换算,注入的时刻一并归一——标记是那个瞬间的属性,与调用方时区无关。用户列表标签和用户页的「标记完成 /
重置」按钮同步改口径,否则页面显示和实际跑不跑对不上。
- **多个用户共用一套 M7A 时,差分宇宙与货币战争从第二个用户起永远记不到完成。** M7A
的周常时间戳按安装目录存、不按游戏账号存:上一个用户打满后写进共享的 `config.yaml`,下一个用户的 patch 以它为底合并,M7A
就跳过积分复核、不再打印 MAS 唯一认的完成 marker,于是天天重跑。把两个时间戳归零,并同时加入 patch 白名单(否则
`merge_whitelist` 会丢掉)和 `M7A_MANAGED_STAGE_KEYS`(否则
`_apply_managed_patch` 会用 native 值覆盖回去)——与日常 patch 处理
`echo_of_war_timestamp` 是同一口径。

## M9A

- **未配置任务队列的用户运行时抛 Python 异常。** 代码给只读 property `UserItem.result`
赋值,`AttributeError` 顶掉了本该显示的「未配置任务队列或队列为空」。`Task_Queue` 默认就是 `[]` 且
`check()` 不校验队列,新建用户不加任务直接跑就必中。
- **配置模板每次运行都被删掉。** `prepare()` 的注释写「仅保留 default.json」,实际
`glob("*.json")` 把它一起删了,而它正是 `build_config`
的模板:每轮第一个用户必然落到「使用最小默认配置」,后续用户读到的是 MAS 自己刚写的那份——用户在 M9A 里设的实例级选项从未生效。

## 主页

- **重返未来 1999 的倒计时整体提前一个时区偏移量。** epoch 毫秒转成 `toISOString().slice(0,
19)`,切掉 `Z` 后消费端 `new Date()` 按本机时区解析(东八区偏 8 小时)。保留 `Z` 即可;被 AUTO-MAS-Project#497
删掉的后端接口输出的也是带偏移的时间。

## 发布流程

- **发版后 CNB 上缺当版发行分支。** `build-app.yml` 用 `secrets.GITHUB_TOKEN` 推发行版分支和
tag,而 GITHUB_TOKEN 造成的 push / create 不触发其它工作流,`sync-cnb.yml`
因此不会为发版跑一次。tag 还能靠后续任意一次同步的 `PLUGIN_PUSH_TAGS` 补上,分支没这个待遇。而 beta.3
是第一个捆绑 Runtime 的版本、打包安装默认走 managed 链路,首次克隆受管工作区按 `[cnb, github]`
找这个分支——国内用户在 cnb 上找不到又连不上 github,初始化直接卡死。给 `sync-cnb.yml` 加
`workflow_dispatch`(该触发器是上述限制的明确例外),并在推完分支后 `gh workflow run`
一次。**注意这一步要等本改动进入默认分支后才真正生效**;在那之前 dispatch 会被拒,所以该步骤带
`continue-on-error`,不会阻断发版。已发布的 beta.3 由维护者手动补过同步,CNB 上现已有该分支。
- **Runtime 调用失败只留一句错误码。** `details` 里每次尝试的来源与失败种类被丢掉,于是 cnb 缺分支、github
超时两件事最终只显示后者,真根因被盖住。现在一并写进日志。

## 验证

均在 `.venv` 下实跑:

| 检查 | 结果 |
| --- | --- |
| `python -m pytest tests` | 738 passed, 3 skipped, 163 subtests |
| `python -m pytest tests --collect-only -q` | 741 collected,exit 0 |
| `python -m ruff check app tests` | 无本次引入的问题(剩余 I001 已逐个比对确认是 dev 上既存的)
|
| `yarn typecheck` | exit 0 |
| `yarn lint` | exit 0 |
| `yarn test` | 418 passed,1 failed |

前端那条失败是 `backendService.test.ts > managed 模式` 超时,**在 dev 上就是红的**:我把改动过的
`backendService.ts` 换回 dev 原版单跑该文件,同样失败。

`yarn format` 会顺带重排十几个本次无关的文件(dev 上本来就没格式化过),已逐个还原,diff 里只有本次真正改到的文件。

另按 `tests/AGENTS.md`「功能边界或 bug 边界的测试不提交」,本轮写的三个回归测试只在本地跑、不进版本库,覆盖
`build_runner_environment` 的源码解析路径与 `PYTHONSAFEPATH`、HSR
日/周标记在服务器换日边界两侧的取值、以及项目指纹对运行期产物(含带标记的 `maafw/` 覆盖层)的排除:**共 11
个用例,本地全部通过**。

## 没有收进来的

- Runtime 侧不接受用户配置的代理(`HTTPS_PROXY` 没有透传给子进程)——那在 AUTO-MAS-Runtime
仓,不能和这个 PR 一起提。
- 审计里另外几条需要设计决定的,例如 HSR 的差分宇宙与货币战争共用一个
`WeeklyCompletedThisWeek`(要加配置字段和迁移)、MFW 更新事务中断后没有恢复入口。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
- 路径 B 下把队列里出现的战斗组从原生一条龙副本剔除,队列开关同时管住执行层与原生一条龙两侧
- 原生副本已无启用任务时跳过启动原生一条龙的阶段,避免 BetterGI 空跑不退出、任务一直结束不了
- 保存用户配置时按队列清理 Plan 中不再被引用的战斗实例
- res/version.json 的 BetterGI 条目收敛为一条
…gon-config

# Conflicts:
#	app/api/scripts.py
#	app/models/schema.py
#	app/task/BetterGI/ScriptConfig.py
#	frontend/src/api/services/Service.ts
#	frontend/src/i18n/locales/en-US.ts
#	frontend/src/i18n/locales/ja-JP.ts
#	frontend/src/i18n/locales/zh-CN.ts
#	res/version.json
- 合并 upstream/dev 时冲突区被 dev 的 ZZZ-OD 端点占据,补回 /bettergi/one-dragon/settings、/bettergi/one-dragon/plan/step-enabled、/bettergi/global-domain/settings、/bettergi/global-stygian/settings、/bettergi/domain-catalog、/bettergi/script-group/save
- 前端 src/api 由 openapi 生成器基于本地后端重新生成,未手改生成文件
- /user/update 恢复「队列为唯一真相源」逻辑:保存队列时同步清理 Plan 中不再被引用的战斗实例
- /bettergi/one-dragon/custom-groups 恢复 userId 参数,用户独立配置下按 per-user 副本读取自定义组
- 前端对齐重新生成后的接口:修正一条龙步骤启用接口名、补齐 OneDragon 的 Plan 与 UseExecutionLayer 默认值
- src/api 由 openapi 生成器重新生成
- main.py 启动时剔除 Runtime/uv run 注入的 VIRTUAL_ENV 与 UV_PROJECT_ENVIRONMENT:
这两个变量会随进程环境传给所有被 MAS 拉起的子进程,外部脚本自己的 uv 会把 项目环境解析到 MAS 运行时 venv
上、甚至尝试删除该目录(ZzzOd 启动器报 「运行环境同步失败」并损坏 venv 的根因)
- ZzzOd 自动模式切换启动器前先中止残留的卡死进程,避免下一轮 open_process 抛「无法同时管理多个进程」,切换永远不会真正发生
- MaaFW runtime pool 环境剔除名单补充上述两个变量,防御同类泄漏

## Summary by Sourcery

清理 MAS 启动链路中的虚拟环境污染,并确保 ZzzOd 自动模式能够可靠切换启动器。

Bug Fixes:
- 修复 MAS 启动链路泄漏 Python/uv 虚拟环境变量及 PATH,避免外部脚本错误复用或破坏 MAS runtime 环境。
- 修复 ZzzOd 自动启动器切换失败后因残留进程占用而无法切换的问题。

Enhancements:
- 加强 MaaFW runtime、runner 与 pip 环境构建时的环境隔离,防止 MAS 的虚拟环境变量传递给外部项目。

<details>
<summary>Original summary in English</summary>

## Summary by Sourcery

清理 MAS 启动链路中的虚拟环境污染,并确保 ZzzOd 自动模式能够可靠切换启动器。

Bug Fixes:
- 修复 MAS 启动链路泄漏 Python/uv 虚拟环境变量及 PATH,避免外部脚本错误复用或破坏 MAS runtime 环境。
- 修复 ZzzOd 自动启动器切换失败后因残留进程占用而无法切换的问题。

Enhancements:
- 加强 MaaFW runtime、runner 与 pip 环境构建时的环境隔离,防止 MAS 的虚拟环境变量传递给外部项目。

</details>

<details>
<summary>Original summary in English</summary>



</details>

<details>
<summary>Original summary in English</summary>



</details>
CHANGELOG.md 是唯一手写来源,res/version.json 等由它生成。此前该条目被直接手改进 version.json,导致 CI「检查 CHANGELOG.md 与生成物一致」失败。现把条目补回 CHANGELOG.md 的 v5.5.0-beta.3 新增分类,并运行 scripts/changelog.py sync 重新生成 version.json,使检查通过。
三处独立修复,都来自 v5.5.0-beta.3 发布后对 **5 台用户机器**的排查(debug 包、Runtime NDJSON
日志、Sentry、两次真机 `repair` 输出)。

## 1. Runtime 拿不到用户配的代理

`buildRuntimeEnv` 只注入 `AUTO_MAS_TELEMETRY` 与 `AUTO_MAS_ENV`,用户在设置里填的
`Update.ProxyAddress` 从来没有传给 Runtime。而 Runtime 的
go-git(`plumbing/transport/http/common.go` 用
`http.DefaultTransport`)与镜像下载器(`internal/mirror/downloader_client.go` 的
`http.DefaultTransport.Clone()`)本来就认 `HTTP(S)_PROXY`,只是没有人设过。

结果:国内用户配了代理,受管工作区首次克隆在 cnb 之后落到 github 兜底时照样裸连 github.com。真机日志里两次
`ls-remote` 各超时 21 秒,一次 clone 收数据 18 分钟后失败。

**透传前严格校验**。真机上见过用户把模拟器安装路径填进这个字段:

```json
"Update": { "ProxyAddress": "D:\\虚拟C盘\\MuMuPlayer-12.0\\nx_main" }
```

(同一份配置里出现 353 次,不是手滑。)原样导出成 `HTTPS_PROXY` 会让 Runtime
一条网络路都走不通,比不设代理更糟,所以解析不出合法 URL、协议不在 `http/https/socks5/socks5h`
白名单、或没有主机名的一律记 warn 后当作没配。

### ⚠️ 需要维护者确认的行为扩大

这三个变量会被 Runtime 原样传给 `uv run` 再传给后端——`internal/uv/runner.go` 的
`buildEnvironment` 整份复制 `os.Environ()`,只过滤 `UV_*` 和四个 `AUTO_MAS_*`。所以:

- **uv** 的依赖下载会走代理(用户选的是清华/阿里等国内源,Clash 规则模式下多半 DIRECT,全局模式下会变慢);
- **后端** 的 httpx/requests 默认
`trust_env=True`,此前只在更新检查里显式用代理,之后所有出站都会跟着走。

对「特意配了代理」的用户这多半正是所求,`NO_PROXY`
固定到本机回环也是因此必需。但这是一次行为扩大,**如果不接受,请直接否掉这一条**,彻底的做法是 Runtime 侧加 `--proxy`
只作用于自己的出站(需要 Runtime 单独发版)。

## 2. 初始化失败日志丢掉 `result.details`

此前只记 code + message。而定位失败真正需要的东西 Runtime 全放在 `details` 里:

- `UPDATE_STATE_AMBIGUOUS`(「仓库更新现场无法安全判定」)在 Runtime 侧有 **20
来个抛出点**,`environment_unreadable` / `prepared_update_missing` /
`transaction_commit_mismatch` / `directory_identity_changed` …… 只有
`details.reason` 分得出是哪一个;
- 镜像轮换失败也只有 `details.attempts` 说得出是哪个源、因为什么挂的。

真机上有用户 9 次启动全部 `UPDATE_STATE_AMBIGUOUS`,日志发过来仍然无法定位到具体分支。补充说明:Runtime
自己的 operation log 也不记失败(9 个文件 2468 行,`level` 分布是 `{'info': 2468}`,零 warn
零 error),所以前端这一行是目前唯一的落点。

`logPath` / `stderr` / `checks` 已由别处单独取用,不重复进这一行;超长截断到 1000 字符。

## 3. AUTO-MAS-Project#641 的 CNB 同步 dispatch 到了错误的 ref

AUTO-MAS-Project#641 让 `build-app.yml` 在推完发行版分支后 `gh workflow run sync-cnb.yml`,方向对,但
`--ref` 给的是 `$GITHUB_REF_NAME`(构建所在分支)。

`sync-cnb` 的 checkout 是 `ref: ${{ github.ref }}`,而 git-sync 只把检出的那个 ref
连同全部 tag 推过去,**不是整库镜像**。实测反证:beta.3 发版当天
12:34(`codex/sync-github-from-dev`)与 12:48(`main`)各跑过一次 sync 且都
success,CNB 上照样没有
`release/v5.5.0-beta.3`;直到有人把提交推到该分支本身(15:26)才同步过去。dispatch 到构建分支等于又推了一次
dev。

改成 `--ref "release/${{ needs.build.outputs.version_tag }}"`。AUTO-MAS-Project#641 加的
`continue-on-error: true` 保留——`workflow_dispatch` 必须在默认分支上才可被调起,main 上的
`sync-cnb.yml` 目前还是旧的,**在 dev 合进 main 之前这一步仍会失败,下次发版还需要人工补推**。

## 验证

在 `D:\MAS\code\trees\dispguard`(v5.5.0-beta.3 基线 `3d34bddd`):

| 检查 | 结果 |
| --- | --- |
| `yarn typecheck` | exit 0 |
| `yarn lint` | exit 0 |
| `yarn test` | 44/45 文件通过,439/440 用例通过 |

唯一失败的是 `electron/services/backendService.test.ts > managed 模式 > 不传
--repo、不先跑 environment ensure,--app-root 就是用户数据根`(5 秒超时)。**已在干净的
`3d34bddd` 上复跑确认同样失败**,与本 PR 无关,未在此处修。

`yarn format` 会顺带改 17 个与本次无关的文件(dev 上本来就没格式化过),已全部还原,本 PR 只含上述 4 个源文件加
CHANGELOG / version.json。

新增单测覆盖代理透传的合法值、socks5、socks4 拒绝、裸 host:port
补协议、本地路径、非法协议、缺主机名、空值、`Config.json` 为 `null` / 数组、凭据遮蔽,以及 details
摘要的保留/剔除/截断。

## 复核后的修正(第二个提交)

经独立复核发现并已修:

- **`Config.json` 内容为字面量 `null` 时会抛异常**。`JSON.parse('null')` 合法地返回
`null`,重构后取字段直接抛出去,而这个函数正是「初始化卡住」时唯一还能跑的那段;旧实现整块在 `try` 里,反而被 catch 成
warn + 缺省。已补类型守卫。
- **裸 `主机:端口` 写法与后端口径不一致**。`app/core/config.py` 的 `GlobalConfig.proxy`
一直会给无协议地址补 `http://`,用户填 `127.0.0.1:7890` 后端认、这里不认,结果就是「更新检查走了代理、Runtime
仍在裸连」。已对齐,但**只对 host 形状的输入补**:WHATWG URL 在 special scheme 下把 `\` 当
`/`,无脑加前缀会让 `http://D:\虚拟C盘\MuMuPlayer-12.0\nx_main` 解析出主机名
`d`,那条模拟器路径反而绕过校验——已有的拒绝用例当场抓到了这个回归。后端放行的 `socks4://` 仍然拒绝,Go 不支持。
- **导出值改为用户写的那串**(仅补协议),不再用
`URL.toString()`:后者会加末尾斜杠、重新编码凭据,与设置页显示的值对不上。
- **日志遮蔽代理凭据**。`http://user:pass@host` 是合法写法,而 `frontend.log` 会被用户贴进
issue。
- **CHANGELOG 三条合并成一条**。AGENTS.md 第 32 行要求一条 PR 只贡献一条记录、用一句话概括。

## 未包含

同一批排查里还有这些,都需要 Runtime 侧改动,不在本 PR:

- `bootstrap.go:257` 的「环境已就绪」判据是纯状态,不碰文件系统;venv 被删坏后 bootstrap 只跑一句 `uv
--version` 就宣布就绪,后端随即以 `No pyvenv.cfg file` 退出;
- `doctor.go:284` 的 venv 检查只查目录存在,全代码库 `pyvenv` 出现 0 次;
- `doctor.go:389` 找 `python/python.exe`,而 uv 实际装在
`python/cpython-<版本>-windows-x86_64-none/python.exe`,doctor 因此恒报「未找到受管
python.exe」;
- `delete_windows.go:531` 删除树遇到任何重解析点立刻整体中止,一个文件都不删(用户 `Remove-Item
-Recurse -Force` 能删掉、Runtime 管理员权限下也删不掉,锁与权限均已排除);
- `uv/dependencies.go:243` 把所有删除失败原因包成
`ENVIRONMENT_REBUILD_FAILED`,连哪个文件都不说;
- Runtime operation log 完全不记失败。

另外 `UPDATE_STATE_AMBIGUOUS` 在界面上是 `retryable: false` +
`run-doctor/contact-support`,用户完全没有出路。**没有**顺手给它加
`rebuild-environment`:`resolveRetryCommand` 对 `repository` 段无视
`needsRebuild`,永远返回 `workspace sync`,加了只会给用户一个假出路,这条同样要等 Runtime
侧提供真正的恢复命令。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
BetterGI 用户配置面板(一条龙队列可视化、配置组设置、秘境选择器、方案配置)
在 frontend 中新增了一批 edit.bettergi* 翻译键,但三个语言包(zh-CN / en-US /
ja-JP)此前均未补,导致界面直接显示原始 key 字符串。

- 补全 93 个缺失的 bettergi* 键(覆盖 BetterGIUserEdit /
  BettergiGroupProjectBody / BettergiDragonGroupSettings 三处组件用到的全部
  edit.* 键,已验证三语言包均 0 缺失)
- 修正英文值中一处未转义的单引号(bettergiDuplicateTip),避免 TS 语法错误

验证方式:脚本扫描三个 BetterGI 组件的全部 edit.* 键,三语言包均 0 缺失,
三个语言包括号配平正常。
后端在就绪前退出,最常见的成因之一是受管 venv 已经损坏——真机上出现过 `pyvenv.cfg` 被删掉、解释器一启动就以 `No
pyvenv.cfg file` 退出的残骸。

`BACKEND_EXITED_BEFORE_READY` 此前只给 `restart-backend` 与
`open-log`,界面上只剩「重试」,而重试永远不会重建环境。Runtime 日志显示用户对同一个失败连点了 21
次,每次都得到同一句报错,没有任何自助出路。

补上 `rebuild-environment`。这张表是 Runtime 错误码表的镜像,Runtime 侧同一改动为
T13.17,同时修正了 `doc/架构设计.md` 里错误码表(917 行)与 Electron 返回示例(398
行)互相矛盾的地方——示例本来就写着 `rebuild-environment`。

## 验证

| 检查 | 结果 |
| --- | --- |
| `yarn typecheck` | exit 0 |
| `yarn lint` | exit 0 |
| `yarn vitest run electron/services/runtimeUpdateService.test.ts` | 28
passed |

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Sourcery 摘要

为后端启动失败场景提供重建运行环境选项,改善运行时错误恢复体验。

新功能:
- 为后端就绪前退出的运行时错误增加「重建运行环境」修复入口。

问题修复:
- 修复受损虚拟环境导致用户只能反复重试、无法自助恢复的问题。

日常维护:
- 同步更新变更日志和版本信息。

<details>
<summary>Original summary in English</summary>

## Sourcery 总结

为后端启动失败场景提供可重建运行环境的恢复选项,改善运行时错误处理体验。

新功能:
- 为后端就绪前退出的运行时错误增加“重建运行环境”修复入口。

问题修复:
- 解决虚拟环境损坏导致用户只能反复重试、无法自行恢复的问题。

文档:
- 修正架构设计文档中的运行时错误码表与 Electron 返回示例不一致的问题。

杂项:
- 更新变更日志和版本信息。

<details>
<summary>Original summary in English</summary>

## Summary by Sourcery

为后端启动失败场景提供可重建运行环境的恢复选项,改善运行时错误处理体验。

New Features:
- 为后端就绪前退出的运行时错误增加「重建运行环境」修复入口。

Bug Fixes:
- 解决受损虚拟环境导致用户只能反复重试、无法自行恢复的问题。

Documentation:
- 修正架构设计文档中的运行时错误码表与 Electron 返回示例不一致问题。

Chores:
- 更新变更日志和版本信息。

</details>

</details>

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: ClozyA <aoxuan233@gmail.com>
Closes AUTO-MAS-Project#614

## 问题

`TypeError: Cannot read properties of undefined (reading
'Official')`(Sentry `AUTO-MAS-DESKTOP-W`),MAA 用户配置页**打开即整页渲染失败**。

`loadActivityStageOptions` 把 `overview.StageByServer` 无条件赋给
`stageOverviewByServer`:

```ts
const overview = response.data as HomeOverviewResponse
stageOverviewByServer.value = overview.StageByServer   // 字段缺席 -> ref 变成 undefined
```

234 行 `ref<HomeOverviewResponse['StageByServer']>({})` 特意给的 `{}`
默认值因此被抹掉。紧接着 `applyServerStageOptions` 里:

```ts
const stageOverview = stageOverviewByServer.value[server]   // ← 先在这里抛
if (!stageOverview) {                                      // ← 这道防线晚了一步
  return
}
```

那道 `if` 只防住「某个服务器没有条目」,防不住「容器本身没了」。而 `applyServerStageOptions` 由 1259
行服务器切换的 watcher 触发,`loadUserData` 填表期间就会跑到——所以是打开页面即崩,不是点某个按钮才崩。

852 行的 `as HomeOverviewResponse` 是无校验断言:后端 `InfoOut.data` 声明为 `Dict[str,
Any]`,`StageByServer` 不进 schema,生成的 API 类型里也没有这个字段,TS 在这里提供不了任何保护。

## 改动

```ts
const overview = response.data as Partial<HomeOverviewResponse> | undefined
if (!overview?.StageByServer) {
  logger.error('活动关卡数据缺少 StageByServer 字段,后端版本可能与前端不匹配')
  activityStageError.value = '加载活动关卡失败:返回数据缺少关卡信息'
  return
}
stageOverviewByServer.value = overview.StageByServer
```

三点:

1. **永不写入 `undefined`**,`{}` 默认值得以保留,watcher 后续再跑也只会安全地走 `return`;
2. 断言放宽成 `Partial<...> | undefined`,**让 TS 强制这次判空**,而不是靠人记得;
3.
缺字段时给出「后端版本可能不匹配」的提示,而不是留一个空的活动关卡列表让用户猜。失败路径**不清空**已有数据,避免把上一次成功加载的结果连带擦掉。

## 关于触发条件

字段为何缺席**未验证**。后端 `app/api/info.py:286` 在 200 路径上总会带上它(`InfoOut.data` 是
`Dict[str, Any]`,不会被 response_model 裁掉),500 路径又已被 `response.code !==
200` 提前拦掉。最可能是后端目录没跟前端一起更新,即 AUTO-MAS-Project#544 那个非原子部署留下的混版安装。

但触发条件在外部不影响这一行该自守——所以本 PR 只修前端这一侧,没有去动后端。

## 本地验证

```
corepack yarn typecheck   # 退出码 0
corepack yarn lint        # 退出码 0
corepack yarn test        # Test Files 1 failed | 43 passed,Tests 1 failed | 413 passed
```

那条失败是 `electron/services/backendService.test.ts > managed 模式 > 不传
--repo、不先跑 environment ensure,--app-root 就是用户数据根`。**已确认是 dev
上的既有失败**:把本次改动 stash 掉后在干净的 `upstream/dev` 上重跑,同一条同样失败(`1 failed | 413
passed`),与本 PR 无关。

`yarn format` 会顺带重排 ZZZ-OD 那批尚未格式化的文件,本 PR **已把它们全部还原**,diff 只有
MAAUserEdit.vue 一个文件。

**没有做真机手测**:复现需要一个 `StageByServer` 缺席的后端,本地起的开发后端总会返回该字段。

## 请审阅

@DLmaster361 这个页面主要是你写的。确认后**请你自行合并**,我不代合。

## Sourcery 摘要

在 MAA 用户配置页面中安全处理缺失的活动阶段数据。

错误修复:
- 当活动阶段数据缺少 `StageByServer` 字段时,防止 MAA 用户配置页面崩溃。
- 当缺少活动阶段信息时,显示清晰的后端兼容性错误,同时保留之前已加载的数据。

<details>
<summary>Original summary in English</summary>

## Sourcery 摘要

在 MAA 用户配置页面中安全处理缺失的服务器活动阶段数据。

错误修复:
- 当后端响应缺少服务器阶段数据时,防止 MAA 用户配置页面崩溃。
- 当缺少必要信息时,显示清晰的后端兼容性错误,同时保留之前加载的活动阶段数据。

杂项:
- 在更新日志中记录 MAA 用户配置页面崩溃修复。

<details>
<summary>Original summary in English</summary>

## Summary by Sourcery

Handle missing per-server activity stage data safely in the MAA user
configuration page.

Bug Fixes:
- Prevent the MAA user configuration page from crashing when backend
responses omit per-server stage data.
- Display a clear backend compatibility error while preserving
previously loaded activity stage data when required information is
missing.

Chores:
- Record the MAA user configuration page crash fix in the changelog.

</details>

</details>

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: ClozyA <aoxuan233@gmail.com>
Closes AUTO-MAS-Project#620

## 问题

`get_device_info` 用 `if_merge_std=True` 跑 `MuMuManager info -v`,MuMu
自己的**埋点**和 **C++ 日志**因此和设备 JSON 混在同一份 stdout 里。`mumu.py` 里 5 处
`json.loads` 都要求整段是纯 JSON,多一行日志就整条失败——**而那份设备 JSON 本身是完整可用的**(`6K` 的事件里
`is_android_started: true` 都在,只是尾部多了一行日志)。

近一日:`1M` 1,943 条(自 08-20 累计 2,113)、`6G` 1 条、`6K` 1 条。`1M`
是模拟器族里事件量最大的一条。

需要说清楚**这条和「模拟器自身故障」不是一回事**:`WinError 5` / `WinError 2`
那批确实是用户侧环境问题,不该我们修;这批是我方解析口径过严。

## 改动

新增 `MumuManager._decode_polluted_json(text, prefer=None)`:扫出输出里**所有**顶层
JSON 值,由 `prefer` 判据挑出期望的那一份,都不命中时退回第一个,一个都解不出来才抛 `JSONDecodeError`。

**不能简单取第一个** —— 埋点 `add record:{"_track_id":...}` 本身也是合法 JSON,而且常常排在设备
JSON **之前**,取第一个会把埋点当成设备信息。所以 5 个调用点各带自己的判据:

| 调用点 | prefer |
| --- | --- |
| `getStatus` / `getInfo` / `list_devices` | `_has_device_entries`(有
`index` + `name`) |
| `_get_adb_address` | 能解析出 host/port |
| `_get_app_state` | dict 且 `state` 是 str |

## 本地验证

```
.venv/Scripts/python.exe -m pytest tests -q
691 passed, 3 skipped, 151 subtests passed in 9.29s          (dev 基线是 682,+9 为本 PR 新增)

.venv/Scripts/python.exe -m ruff check app/utils/emulator/mumu.py   # All checks passed
```

新增 `tests/tools/test_mumu_json_parse.py` 9 条(纯解析逻辑,按 `tests/AGENTS.md`
属于该提交的纯逻辑测试)。样本用的是 Sentry 事件里的真实污染形态:

- 尾部 `[*** LOG ERROR #1 ***] ... {bad_weak_ptr}`
- 头部 `add record:{"_track_id":...,"event":"$SignUp",...}`

**这些样本在改动前确实是炸的**,且报错与 Sentry 上一字不差:

```
尾部 C++ 日志: json.loads -> Extra data: line 5 column 1 (char 150)     ← 对应 6G
头部埋点:     json.loads -> Expecting value: line 1 column 1 (char 0)   ← 对应 1M
两者都有:     json.loads -> Expecting value: line 1 column 1 (char 0)
```

其中一条专门断言「埋点排在前面也不能被当成设备信息返回」。

**没有做真机手测**:本地这台 MuMu 不会往 stdout 写埋点,复现不了污染。解析是纯函数、由上面 9 条覆盖;但真机上
`getInfo` 拿到的输出格式如果和我构造的样本有出入,欢迎指出。

## 请审阅

@qiyinxi `app/utils/emulator` 是你维护的。确认后**请你自行合并**,我不代合。

## Sourcery 总结

允许 MuMu 命令解析从混入遥测数据和原生日志的标准输出中恢复有效的模拟器数据。

错误修复:
- 使 MuMu 设备、ADB 和应用状态解析能够适应命令输出中混入的遥测数据和原生日志,同时仍选择目标 JSON 负载。

增强功能:
- 添加共享的污染输出 JSON 解码功能,并支持针对负载的选择条件和回退行为。

测试:
- 添加针对前置遥测数据、尾随日志、负载选择、回退行为以及无效或空输出的专项测试。

<details>
<summary>Original summary in English</summary>

## Sourcery 总结

提高 MuMu 命令输出的解析容错性,确保混入日志时仍能读取模拟器信息。

Bug 修复:
- 使 MuMu 模拟器、ADB 和应用状态解析能够从混入遥测数据或原生日志的命令输出中恢复有效的 JSON 信息。

增强功能:
- 新增可识别并选择目标 JSON 负载的通用污染输出解析能力,避免将遥测数据误判为设备信息。

测试:
- 新增针对前置遥测、尾随日志、负载选择、回退行为及无效输出的解析测试。

<details>
<summary>Original summary in English</summary>

## Summary by Sourcery

提高 MuMu 命令输出解析的容错性,确保混入日志时仍能恢复有效的模拟器信息。

Bug Fixes:
- 修复 MuMu 命令输出混入遥测数据或原生日志时无法读取设备、ADB 和应用状态信息的问题。

Enhancements:
- 新增可从污染输出中识别并选择目标 JSON 负载的通用解析能力,避免将遥测数据误判为设备信息。

Tests:
- 新增覆盖前置遥测、尾随日志、负载选择、回退行为及无效输出的 MuMu JSON 解析测试。

<details>
<summary>Original summary in English</summary>

## Summary by Sourcery

提高 MuMu 命令输出解析的容错性,确保混入日志时仍能恢复有效的模拟器信息。

Bug Fixes:
- 修复 MuMu 命令输出混入遥测数据或原生日志时无法读取设备、ADB 和应用状态信息的问题。

Enhancements:
- 新增可从污染输出中识别并选择目标 JSON 负载的通用解析能力,避免将遥测数据误判为设备信息。

Tests:
- 新增覆盖前置遥测、尾随日志、负载选择、回退行为及无效输出的 MuMu JSON 解析测试。

</details>

</details>

</details>

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: ClozyA <aoxuan233@gmail.com>
## 问题

虚拟显示器(AUTO-MAS-Project#608)是整轮任务开始挂一块、结束拆掉。任务之外的时间桌面仍旧只有一块幻影屏,
跨任务留存的模拟器与游戏窗口就在那段时间里被压小、并被程序自己写进配置——坏尺寸一旦落盘,
下一轮任务再插屏也纠正不回来。另外无头机器上每跑一轮任务就插拔一次,一天几十次拓扑变更,
而驱动本身受不了快速反复插拔(`_add_with_retry` 那个重试就是为此写的)。

## 改动

- 改成常驻监测:后端在跑就每 5 秒巡检一次,没有任何真实显示输出就挂上,真实显示器一回来
  就拆掉。判据拆成纯函数 `decide()`;挂着屏时看的是「除自己那块以外还有没有真实输出」——
  自己挂的屏本身也算真实输出,继续用 `has_real_display()` 会一直判成「显示器已恢复」。
- 任务期间不拆:拆屏会把窗口挪到刚接回来的显示器上、尺寸也可能跟着变,而脚本正按坐标点。
  拓扑判据另需连续两次成立才动手,避开切模式、驱动重载、KVM 切换、睡眠恢复的中间态。
- 修掉一处既存的虚拟屏泄漏:`asyncio.to_thread` 被取消不会打断线程,`__enter__` 照样把屏
  插上,而取消发生在 `asynccontextmanager` 的 `yield` 之前、收尾的 `finally` 根本不会执行,
  于是留下一块无人认领也没有记账的孤儿屏(`stop_task` 与关机都会触发)。现在挂屏跑在守卫
  自己的任务里并用 `shield` 隔开调用方的取消;`__enter__` 在屏插上之后才失败的那条也补上
  了就地收尾。
- 失败退避 5 分钟并对同一条原因去重,避免常驻之后刷日志。

## 验证

本地回归 773 passed / 3 skipped;收集门槛 `pytest tests --collect-only -q` 退出码 0。
守卫的功能边界与 bug 边界用例按 `tests/AGENTS.md` 未随 PR 提交。

真机跨夜 9 小时 18 分(Parsec VDD 0.45,物理屏 2560x1600):

```
23:22:19 桌面上没有任何真实显示输出,当前只有系统占位的幻影屏: \\.\DISPLAY1 2560x1600
23:22:21 已挂载虚拟显示器: \\.\DISPLAY30 1920x1080
         ── 中间零状态变化 ──
08:40:02 已拆除虚拟显示器(真实显示输出已恢复)
```

虚拟屏拿到的是独立设备名(`\\.\DISPLAY30`),Windows 没有复用幻影屏的 `\\.\DISPLAY1`,
所以「除自己以外还有没有真实输出」这个判据成立;拆除走的是 DETACH 而不是 LOST 路径。
收尾后桌面与记账文件均干净。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
四个 beta 版本的更新日志合计从 43k 字符压缩到 13k 字符(-70%),
修复更新服务因超过 20k 字符限制出错的问题。

主要改动:
- 移除 beta.3 修复中的 6 对重复条目
- 同专项的修复、变更合并为单条并使用多署名
- 压缩过度详细的功能描述,只保留用户需要知道的信息
- 合并代码清理/开发流程等次要条目

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
## 摘要

- 脚本管理页用户卡片新增标签展示:ZZZ-OD 显示配置来源(用户/直控)、区服与账号(收起仅显 4
位尾号,点击展开并复制)及一条龙任务数;直控模式的事实源是一条龙原生配置,仅显示通用标签避免歧义
- 修复用户上次代理失败时标签仍显示绿色的问题,失败现在显示红色
- 顺带修复 MaaFW 用户卡片不显示标签的问题;区服文案复用编辑页 i18n 键,修复英文界面显示中文
- 绝区零一条龙运行超时默认值从 180 分钟调整为 40 分钟

## Sourcery 摘要

完善 ZZZ-OD 与 MaaFW 用户卡片标签展示,并修正相关状态、国际化及运行超时默认配置。

新功能:
- 在 ZZZ-OD 脚本管理页用户卡片展示用户/直控模式、区服、账号及一条龙任务编排信息,并支持账号展开查看与复制。

问题修复:
- 修复代理失败状态仍显示绿色的问题。
- 修复 MaaFW 用户卡片标签不显示及英文界面区服标签显示中文的问题。

杂项:
- 将绝区零一条龙运行超时默认值从 180 分钟调整为 40 分钟。

<details>
<summary>Original summary in English</summary>

## Sourcery 摘要

增强 ZZZ-OD 和 MaaFW 用户卡片标签,同时修正代理状态颜色、本地化内容以及 ZZZ-OD 超时默认值。

新功能:
- 为 ZZZ-OD 用户卡片添加来源、地区、账号和 OneDragon 任务数量标签,并支持展开显示账号和复制到剪贴板。

错误修复:
- 将失败的代理状态显示为红色,而不是绿色。
- 恢复 MaaFW 用户卡片上的标签,并在各界面使用本地化的地区名称。

维护工作:
- 将 ZZZ-OD OneDragon 运行时默认超时时间从 180 分钟缩短至 40 分钟。

<details>
<summary>Original summary in English</summary>

## Sourcery 总结

完善 ZZZ-OD 与 MaaFW 用户卡片信息展示,并修正代理状态颜色、区服本地化和一条龙运行超时默认配置。

新功能:
- 为 ZZZ-OD 用户卡片增加用户/直控模式、区服、账号和一条龙任务数量标签,并支持展开和复制账号。

问题修复:
- 将上次代理失败状态显示为红色。
- 恢复 MaaFW 用户卡片标签展示,并修复 ZZZ-OD 区服标签的英文国际化显示。

维护:
- 将绝区零一条龙运行超时默认值从 180 分钟调整为 40 分钟。

<details>
<summary>Original summary in English</summary>

## Summary by Sourcery

完善 ZZZ-OD 与 MaaFW 用户卡片信息展示,并修正代理状态颜色、区服本地化和一条龙运行超时默认配置。

New Features:
- 为 ZZZ-OD 用户卡片增加用户/直控模式、区服、账号和一条龙任务数量标签,并支持账号展开与复制。

Bug Fixes:
- 将上次代理失败状态显示为红色。
- 恢复 MaaFW 用户卡片标签展示,并修复 ZZZ-OD 区服标签的英文国际化显示。

Chores:
- 将绝区零一条龙运行超时默认值从 180 分钟调整为 40 分钟。

</details>

</details>

</details>
@TCddddd TCddddd closed this Sep 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

8 participants